A module is a document with a creator of 'uACE' and a type 'dACE'. It should have a resource fork containing a number of resources. The data fork should be empty.
You can create a new module using the "Module template" in the "Development" folder, or you can start from scratch using a resource editor.
ACE Module Resources
For each resource type, the resource bits (purgable, locked etc) should not be altered (they will default to the correct settings when the resource is created).
Unless otherwise specified, no resource names are necessary. However, you can name any resource for your own reference if you desire. As this will increase the size of the module file, you should consider removing all unnecessary resource names in your final version.
If you are using ResEdit version 2.1.x as your resource editor, you should be aware of the bugs in this program, as detailed in the 'Version Info' document.
To edit the 'ACEc', 'ACEm', 'ACEi', 'ACEl' or 'ACEv' resources, you will need to use the resource templates in the file "ResEdit ACE! templates" (for ResEdit) or "Resourcer ACE! templates" (for Resourcer) in the "Development" folder. See Appendix B for more information.
The following resources must be present in a module:
'ACEc' - The ACE control resource
The 'ACEc' resources tell the ACE application how to draw and use each control in the window. There should be one 'ACEc' resource for each control in the 'DITL'. The 'ACEc' resource id's should start at 128, and should be numbered sequentially (with the id incremented by 1) and continuously (i.e with no gaps). The first 'ACEc' resource with id 128 is called the first control number.
The 'ACEc' resource id's are associated with the controls in the 'DITL'. The methods used to achieve this are described in the section "Control numbers and dialog item Id" in "Development (III)".
There should be one (and only one) 'ACEc' resource for each dialog control. Do not create 'ACEc' resources which do not have corresponding dialog controls.
Note that a static text item can also be a control in this sense (a control that displays a value, but cannot be edited). Not all static text items need (or should have) corresponding 'ACEc' resources however.
The names of the control resources are used for printing. Each resource should have a name, which should match, as closely as possible, the name of the control seen by the user in the dialog.
The fields of the 'ACEc' resource are as follows:
• Minimum, Maximum: If the control type is a string, then this is the minimum and maximum allowable lengths for the string. A zero minimum is permitted, and means that a null string is acceptable. If the control type is a numeric, then this is the minimum and maximum allowable values (before any equation is applied). If the control type is a character, then this is the minimum and maximum permitted ASCII character code. If a control value is outside these bounds, the user will be warned when they try to save.
Example (Bard's Tale): The player abilities can vary between 1 and 18. The minimum field is therefore 1, and the maximum field is 18.
When both numbers are negative, the minimum is the number with the highest magnitude, and the maximum is the number with the lowest magnitude.
Example: The position of the spoiler on a racing car is measured as a angle between -40 and -5. The minimum control value is -40, and the maximum is -5.
Note that the 'ACEc' template provided for use with ResEdit defaults to signed long integers for the minimum and maximum fields, so if the maximum field is set to 4294967295 (the largest possible integer), this will appear as -2147483648 (you will need to close the resource and then open it again to see this). However, the value for these fields is correctly interpreted by ACE, so if the control is a unsigned long integer, the above example would still be read as 4294967295 by the ACE application, and not -2147483648.
For an ASCII table of character codes, see Appendix E.
• Offset 1, Offset 2: The offset specifies the position of the variable to be read as a positive number of bytes forward from the file pointer (the current position in the file). The variable will be read from the offset specified in offset 1. When the variable is written to the save file, it is written to offset 1 and to offset 2. If the variable is to be written to only one offset, then offset 1 and offset 2 must be the same.
• Link 1, Link 2: These fields are used to 'link' controls to each other, so that the value of one control can affect another control. See the section 'Control Linking' in "Development (part III)" for more information.
• Type: The control type is the type of variable to be read from the save file. The type must be one of the following:
1. C string (each byte is a character, terminated by a 0 byte).
2. Pascal string (first byte is length, subsequent bytes are characters).
3. Unsigned short: Two byte positive integer, range 0 to 65535.
4. Signed short: Two byte signed integer, range -32767 to 32767.
5. Unsigned long: Four byte positive integer, range 0 to 4294967295.
6. Signed long: Four byte signed integer, range -2147483648 to 2147483648.
7. Byte: A single unsigned byte, range 0 to 255.
8. High nibble: The top four bits of a byte, range 0 to 15.
9. Low nibble: The bottom four bits of a byte, range 0 to 15.
10. Character: A single unsigned byte, range 0 to 255 (but typically 33 to 217 or less).
13. Unsigned short (little endian): As 3 above, but in Intel native format.
14. Signed short (little endian): As 4 above, but in Intel native format.
15. Unsigned long (little endian): As 5 above, but in Intel native format.
16. Signed long (little endian): As 6 above, but in Intel native format.
100 - 107. Bits 0 to 7 of a byte, range 0 to 1.
See Appendix C for more information on big/little endian data.
• Equation to screen: The string number in 'STR#' resource id 129, which parses the file value through the interpreter before putting it on screen, or 0 if no equation is to be used.
• Equation to file: The string number in 'STR#' resource id 130, which parses the screen value through the interpreter before writing it to the save file, or 0 if no equation is to be used.
See the section "Equation Parser" for more information on equations.
'ACEi' - the ACE dialog item mapping resource
The 'ACEi' resource maps controls ('ACEc' resources) to dialog items.
For each DITL resource, there may be a corresponding 'ACEi' resource with the same id. If there is no 'ACEi' resource for a DITL, the ACE application assumes that each control in the 'ACEc' resource maps directly to a dialog item id.
Each 'ACEi' resource should contain one field for each 'ACEc' resource. Each field specifies the corresponding dialog item id for that control number.
See the section "Control Number and Dialog Item Id" in the "Development (III)" document for more information..
'ACEm' - The ACE module resource
The 'ACEm' resource provides information about the save game file.
There should be only one 'ACEm' resource, and it should have a resource id of 128.
The name of the 'ACEm' resource is the name that appears in the Modules menu in the ACE application. This name should be unique and cannot contain the following characters:
; ^ ! < / ( -
The fields of the 'ACEm' resource are as follows:
• Application: A four character string that identifies the application that created the save file. Use ResEdit's Get File Info command to determine the application creator. You can specify a wildcard parameter as '****', which causes ACE! to ignore a save file's creator and look at the document types only. This is useful when an application uses more than one creator, or if many different applications share the save file.
• Document 1 - Document 10: A four character string that identifies the save file document(s). If there are less than 10 document types, the empty fields should contain 4 spaces. If there is more than one save file document, they should be listed continuously (i.e. with no gaps). The order is not significant unless there is a dialog control that specifies the document type (see below).
• Resource type: If the save game data is stored in the resource fork of the save file, then this field specifies the resource type. If the save game data is in the data fork, this field should be left blank (i.e. four spaces)
• Data size: This is the number of bytes to be read by the ACE! application.
1. If there are a known number of slots in a file, then the data size is this number multiplied by the size of each slot.
2. If there is an unknown number of slots in a file, but the maximum possible number is known, then the data size is this maximum multiplied by the size of each slot.
3. If there is an unknown number of slots, and there is no known maximum, then the data size is the number of bytes to the end of the data or resource fork (measured from the offset of the first slot).
At most, this number will be either the data fork length, or the resource fork size.
• Data offset (from start): This is the offset (in bytes) from the start of the data fork. This offset is applied before the offsets in the 'ACEc' resources, but after the "Data offset (from this)". This offset can be positive or negative, the latter being only useful when used in conjunction with the "Data offset (from start)".
• Slot size: In a compound file, this is the offset (in bytes) between characters. The data offsets (from start and from this) are assumed to point to the first character, and the slot size is used to locate subsequent characters. In this case, you will need to specify equations in the STR#138 resource to determine if there is a character in this slot, and if it is the last character. The first equation (id 1) should return the value 1 in the variable 'y' if there is a character in this slot, or 0 if there is not. The second equation (id 2) should return the value 1 in the variable 'y' if this is the last character in the file, or 0 if it is not. The array of variables x[0] to x[9] contain 10 bytes (the exact offset of these bytes within the slot is specified by the 'Slot equation offset' field - see below).
Example: The simplest (and most common) method used in save games to designate the presence of a character is a 0 byte at the beginning of the slot. The equation used to handle this case would be 'if (x[0]<>0) then y=1 endif'.
For simple (non-compound files) this field is zero.
• Resource id: If the save game data is in the resource fork, then this is the id of the resource.
• File type control: The control number of the control that determines the file type of the character file when it is saved (or zero if there is no such control). The value of this control (before any equation is applied) is matched to an item in the list of document types - Document 1 to Document 10.
Example: Bard's Tale has ten character classes, each with their own file type and icon. If the user changes the class of a character via the class pop-up menu, this automatically changes the file type and hence the file icon when the character is saved.
The value of the file type control can be parsed by an equation before being used to determine the document type. If there is an equation present in the STR#139 resource, id 1, it will be used to parse the control value. The control value is placed in the variable 'x', and the equation should return a number. Note that this does not actually affect the control value written to the file. If there is no equation in this resource, or if the STR#139 resource is not present, the control value will not be parsed.
Example: The Realmz module uses a complicated equation to match the 19 different castes to 7 different file types.
A file type control can only be used with non-compound files.
• Slot equation offset: In a compound file, this is the offset in the slot from which the 10 bytes stored in the array x[0] to x[9] are taken. These 10 bytes are used to determine whether there is a character in the slot (see the 'Slot size' field above).
Example: In 'Heroes of Might & Magic - Towns' the first town appears 288 ($120) bytes after the string 'Celia' ('Data offset (from this)' is 'Celia' and 'Data offset (from start)' is $120). Each subsequent town is located +100 ($64) bytes from this offset (Slot size is $64). If there is a town at each offset, the town will have a name. The name is located +79 bytes from the start of each town offset ('Slot equation offset' is +79).
• Data offset (from this): A sequence of characters to search for in the save game. This offset is applied before all other offsets. When located, the file pointer is positioned at the start of the sequence of characters. This type of offset can only be used when the save game data is in the data fork of the file.
Example: In Marathon save game files, the player information is preceded by the sequence of characters 'plyr'.
To enter 'untypable' characters (byte values below 32 for example), open the 'ACEm' resource in hex editing mode. To do this in ResEdit, choose Open Using Hex Editor from the Resource menu. You can then append the bytes directly onto the end of the resource. This field is a pascal string, so it must be length prefixed.
'ACEv' - The ACE version resource
These resources are used to indicate if the module is compatible with earlier versions of ACE. Create a 'ACEv' with an id equal to the version of the ACE application you want to provide compatibility information for. The first version of ACE to read 'ACEv' resources was version 1.1.1, so you do not need to create 'ACEv' resources for ACE version 1.0 or 1.1 (id 100 or 110).
Example: A module designed for ACE! version 1.5 should contain six 'ACEv' resources with id 111, 120, 121, 130, 140 and 141 to indicate to ACE! version 1.1.1, 1.2.0, 1.2.1, 1.3.0, 1.4.0 and 1.4.1 that your module is (or is not) compatible with those versions.
See Appendix F for backwards compatibility information.
'dctb' - The dialog colour table
This resource is created when a custom colour scheme is selected in the 'DLOG' editor. You should not edit or create this resource directly.
'DITL' - The dialog item list
This resource specifies all the items in a dialog. There should be at least one 'DITL' resource, with an id of 128. If you want to use the new appearance manager group boxes and separator lines, you will need to create a second 'DITL' with id 129. If there are two 'DITL' resources, ACE! will use 'DITL' id 128 for systems that don't have the appearance manager, and 'DITL' id 129 for systems that do. If there is only one 'DITL' (id 128), it will be used for both appearance and non-appearance manager systems.
Hint: Design the 'DITL' id 128 for non-appearance manager systems first, then duplicate the resource and change its id to 129). Then delete the separator pictures and label text from 'DITL' id 129 and add the new group box/separator line controls.
Note that the dialogs in a module are referred to as 'windows' in the user documentation. This is not strictly true, but users perceive these kind of dialogs as being windows, and it make it easy to distinguish between these dialogs and other dialogs.
'dlgx' - Extended dialog template
This resource is used by the Appearance manager. If you have a 'DITL' id 129, then this resource should have an id of 129. If not, it should have an id of 128. This resource should not be edited.
'DLOG' - The dialog template
This resource specifies a number of miscellaneous options for the dialog. There should be at least one 'DLOG' resource, with id 128. If you have a second appearance manager 'DITL' id 129, then you should have a second 'DLOG' also with id 129.
• The position of the dialog (it's offset from the top left corner of the screen) is irrelevant - ACE positions each dialog automatically.
• The dialog size can be specified, although this is usually done automatically by the 'DITL' editor.
• The dialog type should look like this:
(a title bar and no border, scrollbars or resize button)
• The "Initially visible" checkbox should be unchecked, and the "Close box" check box should be checked.
• The colour table should be set to custom for 'DLOG' id 128 only. Change the content colour to any colour except plain white. ResEdit will warn you that this will create a dialog colour table ('dctb'). Click on the OK button. Now change the content colour back to plain white. This step is necessary to make the Macintosh Dialog Manager handle the dialog as a colour dialog, rather than a black and white dialog (some extensions that alter the colour of dialogs and dialog items will not work if the dialog is treated as a black and white dialog).
Under the Appearance manager, all dialogs are treated as colour, hence it is unnecessary to choose a custom content colour for 'DLOG' id 129.
• The dialog characteristics (accessed through the DLOG menu in ResEdit) should be left at their default values (no window title, refCon = 0 and ProcID = 4)
'hfdr' - Finder balloon help
Under MacOS 8, this resource tells the Finder to display the text in the 'STR#' resource id 131 when balloon help is activated and the cursor is over the ACE! module document. In System 7, this resource will have no effect (a generic document help balloon is displayed). You should not edit this resource.
'STR ' - Strings
There should be one 'STR ' resource with an id of -16397. On MacOS 8 systems, the text in this string is displayed if the user tries to open or print the module from the Finder.
'STR#' - Indexed string list
id 128: The module info strings. This resource should contain four strings, which are used in the module info dialog. They are:
String 1: The name of the game.
String 2: The name of the person that created the module.
String 3: Compatibility information. You should indicate what versions of the game your module has been tested with.
String 4: Comments (any other information that is relevant).
String 5: A URL for the author. This is normally an email address (prefixed by 'mailto:') but can be any valid URL. If the author does not have a URL address they wish to link to, this string should be left blank.
If the module uses the equation parser, there will be two equation string resources:
id 129: Equations to convert the save file variables to their on-screen value, as specified in the 'ACEc' resources.
id 130: Equations to convert the on-screen variables back to the save file representation, as specified in the 'ACEc' resources.
id 131 (String 1): This is the text displayed by the System 8 Finder when balloon help is on and the cursor is over the ACE! module document. It is recommended that you do not edit this text (authoring information should be presented in the Get Info dialog, not in the Balloon help).
Other STR# resources may be present for modules that use lists.
'vers' - The version information resource
The 'vers' resource is used to store version numbers and version related information. An ACE module should have two 'vers' resources:
id 1: The version of the module. Fill in all the fields of this resource as appropriate. Use the version number information to distinguish between different versions of your module. This is the version information that appears in the Finder's Get Info window.
id 128: The version of ACE that the module was designed to work with. Enter the version of the ACE application in the version number fields. It is not necessary to fill in any other fields (they are unused).
Depending on the content of the module, the following resources may also be present:
'CNTL' - The control template
A 'CNTL' resource is necessary for each pop-up menu you place in a dialog, and for each appearance manager group box or separator line. If the module uses tabbed windows, you will need a 'CNTL' resource for each tab control (a row of tabs or a pop-up group box)
The first pop-up menu 'CNTL' resource should have an ID of 1000. The first group box or separator line should have an ID of 2000. The first tab control should have an ID of 3000. Fill out the fields as follows:
• BoundsRect: This is, respectively, the top left coordinate (X and Y) and the bottom right coordinate (X and Y) in pixels of the item rectangle. Note that the top left position is actually determined by the position of the 'CNTL' item in the 'DITL' resource. The Set button allows you to set these fields by dragging the cursor.
Hint: The BoundsRect field for a pop-up menu is 0 0 20 (width of menu + title in pixels).
Hint: To make group boxes for your appearance manager dialog, open the non-appearance manager dialog id 128, and for each group box, record 1. the top coordinate of the group box title, 2. the left coordinate of the left separator line, 3. the top coordinate of the bottom line plus one, and 4. the left coordinate of the right line plus one. Enter these values in this order into the BoundsRect. This ensures that your group box is exactly the same size as the (fake) group box in 'DITL' id 128.
Note: The above method lets you define appearance manager group boxes even if your system doesn't have the appearance manager.
The orientation of a separator line is determined by the orientation of the BoundsRect.
Alternatively, you can copy values from any existing 'CNTL' resource, and modify the second to last number (which determines the height) and the last number (which determines the width). The difference between the first and third number should be 21 exactly for pop-up menus.
• Value: This should be 0, except for CNTL resources which are associated with an appearance manager 'row of tabs' control - in this case, Value should be 128. For lists, this should be the id of the corresponding 'ldes' resource.
• Visible: This should be True.
• Max: For pop-up menus and pop-up group boxes, this determines the position of the pop-up menu title, measured in pixels from the left hand edge of the menu. If you do not want a title for your pop-up menu, set this field to 0. For group boxes, this field should always be 100. For all other types of control, this should be 0.
• Min: This field should contain the resource id of the 'MENU' resource used by the pop-up menu or pop-up group box. It's ok for multiple 'CNTL' resources to use the same 'MENU' resource if the dialog has two or more pop-up menus that are the same. For all other types of control, this field should be 0.
• ProcID: This should be 1008 for pop-up menus, 160 for group boxes, 144 for separator lines, 128 for a row of tabs, 162 for a pop-up group box and 353 for a list.
• RefCon: This should be 0. For lists, it is the list number (1 for the first list, etc).
• Title: The text that appears to the left of the pop-up menu, or at the top left of the group box. If a pop-up menu or group box is to have no title, leave this field blank. For other controls, leave this field blank.
See Appendix G for a table that summarises the 'CNTL' resource field values.
Note that in order to see in the 'DITL' the changes you have made to a 'CNTL' resource, you must close the 'CNTL' resource first. It may also be necessary to force the 'DITL' to redraw it's contents (by using the WindowShade, or closing the 'DITL' and reopening it).
'MENU' - The menu resource
The 'MENU' editor lets you specify the actual contents of the pop-up menu. The first 'MENU' resource should have an id of 1000. The following points should be noted:
• The entire menu should be enabled.
• The menu title is not used (the actual title is determined by the Title field in the corresponding 'CNTL' resource). However, it is probably good practice to enter the menu title for clarity.
• You may add separator lines.
• Do not create sub-menus of pop-up menu's.
• Do not put any marks beside menu items. You cannot set the default item by placing a mark.
• Do not make a command key for a pop-up menu item.
The first menu item is mapped to the minimum field of the corresponding 'CNTL' resource. Subsequent menu items are incremented by one (separator items are included, even though they can't be selected by the user).
Example: In Realmz, the Caste pop-up menu contains 8 items. The minimum field of the 'ACEc' Caste resource is 1. When the user selects the first item in the pop-up menu, this is written to the file as 1.
'PICT', 'cicn' - Picture and colour icon resources
You can add pictures and icons to your dialog. Bear in mind that any artwork (pictures and icons) used in the game are probably copyright (and you should assume they are unless otherwise stated). It is not unreasonable however to draw your own pictures or icons based on the original artwork. Fair use is the key - copying and pasting pictures and icons wholesale is illegal.
'scpt' - Script resources
This is the standard resource type for a script. 'scpt' resources are created by a script editor. See "Development (Scripts)" for more information.
'tab#' - the tab information resource
The 'tab#' resource is used by the appearance manager to draw a row of tabs. This resource is only necessary if the module supports tabbed windows. You must include and fill out the fields of this resource even if your tabbed windows use only pop-up menu tab controls. There should be only one 'tab#' resource with a resource id of 128. See "Development (Tabs)" for more information on tabbed windows.
'ldes' - the list description resource
This resource is used to describe appearance manager savvy lists. This resource is only necessary if the module supports lists. See "Development (Lists)" for more information on lists.
'TEXT' - Text resources
The text resource holds the description for each script (see 'scpt' resource above). Refer to "Development (Scripts)" for more information.
